CKYC Legal Entity Download Docker Solution
The following document highlights the details of the CKYC Legal Entity Download Docker Solution.
API Description
Objective
The HyperVerge CKYC Legal Entity Download Docker Solution enables Regulated Entities (REs) to search and download CKYC records for legal entities (companies, organisations) from CERSAI via a self-hosted Docker-based setup, without direct dependency on HyperVerge's cloud.
Note
For legal entity records, OTP consent is not required. Such downloads follow the non-OTP method using an authentication factor (date of incorporation, mobile number, email, or pincode).
Process
The Legal Entity Download API handles both search and download operations for legal entity CKYC records in a single call. To perform only a search, set returnOnlySearchResponse to yes. To perform a download, provide at least one authentication factor (doi, mobileNo, email, or pincode).
Legal Entity Download API
Use this API to search and optionally download the CKYC record for a legal entity.
API URL
http://localhost:3000/api/v1/legalDownload
Note on URL
Replace http://localhost:3000 with the RE's domain where the CKYC services are hosted.
Overview
The Legal Entity Download API is RESTful and uses standard HTTP verbs and status codes. Responses are in JSON format. Send all parameters as JSON through a POST request.
Method - POST
Authentication
You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to access this API.
Headers
| Header | Mandatory / Optional | Description | Input Format |
|---|---|---|---|
content-type | Mandatory | Defines the media type for the request payload. | application/json |
appId | Mandatory | The application ID shared by HyperVerge. You can find the details in the dashboard's credentials tab | This should be a unique value |
appKey | Mandatory | The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab | This should be a unique value |
transactionId | Mandatory | A unique identifier for tracking a user journey | This should be both unique and easily associated with the user's journey in your application(s) |
moduleId | Mandatory | The module identifier for the CKYC search API. | module_ind_ckyc_search_api |
Inputs
The following table provides the details of the parameters required for the Legal Entity Download API request body:
| Parameter | Mandatory / Optional | Type | Description | Input Format | Default Value | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idNo | Mandatory | String | The ID number of the legal entity. The accepted format depends on the idType value. | <Enter_the_ID_Number> | Not Applicable | ||||||||||||||||||||||||
idType | Mandatory | String | The type of ID being submitted. Accepted values:
| <Enter_the_ID_Type> | Not Applicable | ||||||||||||||||||||||||
entityType | Mandatory | String | Identifies the record as a legal entity. Must be passed for the HyperVerge API to correctly route the request. | legalEntity | Not Applicable | ||||||||||||||||||||||||
doi | Mandatory for downloads; not required for search | String | Date of Incorporation. Used as an authentication factor for downloads. One of mobileNo, doi, email, or pincode must be provided for download. | DD-MM-YYYY | Not Applicable | ||||||||||||||||||||||||
mobileNo | Optional | String | Mobile number for verification. Must be a valid 10-digit Indian mobile number starting with 6-9. Can be used as an alternative authentication factor for download. | <Enter_the_Mobile_Number> | Not Applicable | ||||||||||||||||||||||||
email | Optional | String | Registered email for verification. Can be used as an alternative authentication factor for download. | <Enter_the_Email> | Not Applicable | ||||||||||||||||||||||||
pincode | Optional | String | 6-digit postal code (non-zero). Can be used as an alternative authentication factor for download. | <Enter_the_Pincode> | Not Applicable | ||||||||||||||||||||||||
returnOnlySearchResponse | Optional | String | If set to yes, only the search response is returned. For a subsequent download, call the Legal Entity Download API again with an authentication factor. | yes / no | no | ||||||||||||||||||||||||
returnRecordCountDetails | Optional | String | Returns downloadCount and updateCount in the response. Recommended for downloads. | yes / no | no | ||||||||||||||||||||||||
returnckycRefNo | Optional | String | Returns the CKYC reference number in the ckycRefNo field of the response. | yes / no | no | ||||||||||||||||||||||||
outputImageType | Optional | String | base64: returns images as base64-encoded strings. selfurl: generates presigned URLs for client storage. hvurl: generates presigned URLs for HyperVerge storage. | base64 / selfurl / hvurl | Not Applicable |
Request
curl --location 'http://localhost:3000/api/v1/legalDownload' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--header 'moduleId: module_ind_ckyc_search_api' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'Content-Type: application/json' \
--data '{
"idNo": "<Enter_the_ID_Number>",
"idType": "<Enter_the_ID_Type>",
"entityType": "legalEntity",
"doi": "<Enter_the_DOI>",
"outputImageType": "base64",
"returnOnlySearchResponse": "no",
"returnRecordCountDetails": "yes",
"returnckycRefNo": "yes"
}'
Success Response
The following code snippet demonstrates a success response from the Legal Entity Download API:
- Search Only
- Search and Download
{
"status": "success",
"statusCode": "200",
"result": {
"constitutionType": "",
"constitutionTypeOthers": "",
"ckycNo": "XXXXXXXXXX5658",
"fullName": "",
"doi": "",
"idList": [
{ "STATUS": 3, "TYPE": 2 },
{ "STATUS": 3, "TYPE": "C" }
],
"placeOfIncorporation": "",
"countryOfIncorporation": "",
"tinGst": "",
"tinCountry": "",
"address1": "",
"address2": "",
"address3": "",
"city": "",
"district": "",
"state": "",
"country": "",
"pincode": "",
"poa": "",
"poaOthers": "",
"permAndCorresAddSame": "",
"corresAddress1": "",
"corresAddress2": "",
"corresAddress3": "",
"corresCity": "",
"corresDist": "",
"corresState": "",
"corresCountry": "",
"corresPin": "",
"corresPoa": "",
"proofOfAddress": "",
"resiStdCode": "",
"resiTelNo": "",
"offStdCode": "",
"offtelNo": "",
"faxCode": "",
"faxNo": "",
"mobileCode": "",
"mobileNumber": "",
"email": "",
"decDate": "",
"decPlace": "",
"kycDate": "********",
"updatedDate": "",
"DocSub": "",
"kycName": "",
"kycDesignation": "",
"kycBranch": "",
"kycEmpCode": "",
"orgName": "",
"orgCode": "",
"numIdentity": "",
"numRelated": "",
"numImages": "",
"pan": "",
"form60Submitted": "",
"dateOfBusinessCommencement": "",
"identityVerificationDone": "",
"officiallyValidDoc": "",
"certOfIncorporation": "",
"regcertificate": "",
"articleOfAssociation": "",
"partnershipDeed": "",
"trustDeed": "",
"boardResolution": "",
"powerOfAttorney": "",
"activityProof1": "",
"activityProof2": "",
"imageDetails": [
{ "code": "02", "type": "", "imageUrl": "" }
],
"relatedPersonDetails": [],
"downloadCount": "",
"updateCount": "",
"ckycRefNo": "",
"age": ""
}
}
Search response fields
In practice, CERSAI only returns the following fields for the search response:
ckycNo(masked)ckycRefNofullNameconstitutionTypeplaceOfIncorporationagekycDateupdatedDateidList(type,status)imageDetails(type,imageUrl)
The full response structure is preserved for consistency with the download flow, reducing the need for any client-side transformation logic.
{
"status": "success",
"statusCode": "200",
"result": {
"constitutionType": "",
"constitutionTypeOthers": "",
"ckycNo": "",
"fullName": "",
"doi": "",
"idList": "",
"placeOfIncorporation": "",
"countryOfIncorporation": "",
"tinGst": "",
"tinCountry": "",
"address1": "",
"address2": "",
"address3": "",
"city": "",
"district": "",
"state": "",
"country": "",
"pincode": "",
"poa": "others",
"poaOthers": "OTHER",
"permAndCorresAddSame": "Y",
"corresAddress1": "",
"corresAddress2": "",
"corresAddress3": "",
"corresCity": "",
"corresDist": "",
"corresState": "",
"corresCountry": "",
"corresPin": "",
"corresPoa": "others",
"proofOfAddress": "",
"resiStdCode": "",
"resiTelNo": "",
"offStdCode": "",
"offtelNo": "",
"faxCode": "",
"faxNo": "",
"mobileCode": "",
"mobileNumber": "",
"email": "",
"decDate": "",
"decPlace": "",
"kycDate": "********",
"updatedDate": "",
"DocSub": 1,
"kycName": "********",
"kycDesignation": "********",
"kycBranch": "********",
"kycEmpCode": "********",
"orgName": "********",
"orgCode": "********",
"numIdentity": "",
"numRelated": "",
"numImages": "",
"pan": "",
"form60Submitted": "",
"dateOfBusinessCommencement": "",
"identityVerificationDone": "",
"officiallyValidDoc": "",
"certOfIncorporation": "",
"regcertificate": "",
"articleOfAssociation": "",
"partnershipDeed": "",
"trustDeed": "",
"boardResolution": "",
"powerOfAttorney": "",
"activityProof1": "",
"activityProof2": "",
"imageDetails": [
{ "code": 19, "type": "jpg", "imageUrl": "" },
{ "code": 98, "type": "jpg", "imageUrl": "" }
],
"relatedPersonDetails": [
{
"relationType": "",
"sequenceNo": "",
"ckycNo": "",
"prefix": "",
"firstName": "",
"middleName": "",
"lastName": "",
"dob": "",
"gender": "",
"nationality": "",
"pan": "",
"address1": "",
"address2": "",
"address3": "",
"city": "",
"district": "",
"state": "",
"country": "",
"pincode": "",
"mobileCode": "",
"mobileNumber": "",
"email": "",
"din": "",
"orgName": "",
"orgCode": "",
"photoUrl": "",
"poiUrl": ""
}
],
"downloadCount": "",
"updateCount": "",
"ckycRefNo": ""
}
}
Success Response Details
The following table describes the key fields returned in the Legal Entity Download API success response:
| Parameter | Type | Description |
|---|---|---|
status | string | The status of the request. Returns success on a successful call. |
statusCode | string | The HTTP status code for the response. |
result.ckycNo | string | The CKYC number of the legal entity (masked in search response). |
result.fullName | string | The registered name of the legal entity. |
result.constitutionType | string | The type of legal constitution (e.g. Public Limited Company, Partnership). |
result.doi | string | Date of Incorporation of the legal entity. |
result.placeOfIncorporation | string | The place where the legal entity was incorporated. |
result.idList | array | List of ID types and their verification status associated with the CKYC record. |
result.kycDate | string | The date on which the KYC was completed. Masked in the response (********). |
result.updatedDate | string | The date on which the KYC record was last updated. |
result.imageDetails | array | List of images associated with the CKYC record, returned in the format specified by outputImageType. |
result.relatedPersonDetails | array | Details of persons related to or authorised to transact on behalf of the legal entity. Only returned in the download response. |
result.downloadCount | string | Total number of times this CKYC record has been downloaded. Returned only when returnRecordCountDetails is yes. |
result.updateCount | string | Total number of times this CKYC record has been updated. Returned only when returnRecordCountDetails is yes. |
result.ckycRefNo | string | The CKYC reference number. Returned only when returnckycRefNo is yes. |
Error Responses
The following are sample error responses for the Legal Entity Download API:
- Missing/Invalid Credentials
- Digital Signature Error
- Internal Server Error
{
"status": "failure",
"statusCode": "401",
"error": {
"code": "ER_AUTH",
"message": "Missing/Invalid credentials"
}
}
{
"status": "failure",
"statusCode": "404",
"error": {
"code": "ER_CKYC_SEARCH_AND_DOWNLOAD",
"message": "Digital signature cannot be verified. The certificate is expired."
}
}
{
"status": "failure",
"statusCode": "500",
"error": {
"code": "ER_SERVER",
"message": "Internal server error"
}
}
Error Response Details
A failure response contains a failure status with a relevant status code and error message. The following table lists the error responses for the Legal Entity Download API:
| Status Code | Error Message | Error Description | Error Resolution |
|---|---|---|---|
| 401 | Missing/Invalid credentials | The request is missing or has invalid appId and appKey values. | Verify and provide valid appId and appKey credentials. |
| 404 | Digital signature cannot be verified. The certificate is expired. | The request XML failed digital signature verification on the CERSAI portal. Possible reasons: request XML signed with incorrect signature tag patterns; FI public and private keys do not match; expired digital signature certificate (DSC). | Check the signing configuration or contact HyperVerge support. |
| 500 | Internal Server Error | Kindly check the request headers or contact the HyperVerge team for resolution. | Check the request headers or contact the HyperVerge team for resolution. |